home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / swag9502.zip / XX3402.ZIP / XX3402.DOC < prev    next >
Text File  |  1994-01-28  |  12KB  |  331 lines
  1.  
  2.  
  3.                         XX34 Version 0.2  01/28/94
  4.                    Public Domain Binary Encoder/Decoder
  5.                             by Guy McLoughlin
  6.  
  7.  
  8.  
  9.   WHAT THE HEY IS XX34 ?
  10.  
  11.   XX34 is a utility program that encodes binary files into alpha-
  12.   numeric ASCII text blocks. Once encoded these text blocks can
  13.   be transmitted over text based systems, and then decoded back
  14.   into a copy of the original binary file. XX34 makes the entire
  15.   process quite simple, especially decoding as no editing or
  16.   sorting is required to decode the encoded text blocks.
  17.  
  18.  
  19.   SYNTAX
  20.  
  21.   If you enter "XX3402" on the DOS command-line with no parameters,
  22.   you will see the XX3402 syntax info:
  23.  
  24.     XX3402  Binary Encoder/Decoder  Version 0.2  01-28-94
  25.             Public-Domain Utility by Guy McLoughlin
  26.  
  27.       Usage: XX3402 <E|ES|D|T> [d:][path]<filename> [cols] [rows] [ADn]
  28.  
  29.       Encode Parameters
  30.            <E> Encode binary file (single output file)
  31.           <ES> Encode binary file (split output files)
  32.         [cols] Min = 60, Max = 100 (default = 72)
  33.         [rows] Min = 10, Max = 600 (default = 85)
  34.          [ADn] Alternative delimiter (n = 1..9)
  35.  
  36.       Decode Parameters
  37.            <D> Decode encoded file (Halt on any error  )
  38.            <T> Test encoded blocks (Test for CRC errors)
  39.  
  40.       Examples
  41.         XX3402 E  MYFILE.ZIP (Encode MYFILE.ZIP, using defaults )
  42.         XX3402 ES MYFILE.ZIP (Encode MYFILE.ZIP, split output   )
  43.         XX3402 D  MYFILE.XX  (Decode MYFILE.XX,  using defaults )
  44.         XX3402 T  MYFILE.XX  (Test   MYFILE.XX,  display results)
  45.  
  46.  
  47.   ENCODING/DECODING
  48.   COMMAND-LINE PARAMETERS
  49.  
  50.     Parameter 1 : Type "e" or "E" to encode the input file, creating
  51.                   a single output file containing all encoded text
  52.                   blocks.
  53.  
  54.                   Type "es" or "ES" to encode the input file, creating
  55.                   an output file for each encoded text block.
  56.  
  57.                   Type "d" or "D" to decode the encoded text blocks
  58.                   found within the input file, creating a copy of the
  59.                   original binary file.
  60.  
  61.                   Type "t" or "T" to test the integrity of all encoded
  62.                   text blocks found within the input file.
  63.                   (Useful for checking individual encoded blocks)
  64.  
  65.     Parameter 2 : The name of the input file to be encoded, decoded,
  66.                   or tested. (Accepts optional drive and path strings)
  67.  
  68.  
  69.   OPTIONAL ENCODING
  70.   COMMAND-LINE PARAMETERS
  71.  
  72.     Parameter 3: Column width for encoded plain-text block. Valid range
  73.                  is 60..100, in increments of 4. (ie: 60, 64, 68..100)
  74.                  Default column width is 72.
  75.  
  76.     Parameter 4: Row length for encoded plain-text block. Valid range is
  77.                  10..600, in increments of 1. (ie: 10, 11, 12, 13..600)
  78.                  Default row length is 85.
  79.  
  80.     Parameter 5: Alternative delimiter, for systems where the "*" XX34
  81.                  delimiter may prove to be a problem.
  82.                  Valid range ADn = AD1..AN9.
  83.  
  84.                     AD1 = ':'      AD4 = '='      AD7 = '%'
  85.                     AD2 = '#'      AD5 = '$'      AD8 = '&'
  86.                     AD3 = '@       AD6 = '?'      AD9 = '!'
  87.  
  88.   NOTE: When decoding, XX3402 searches the first 60K of the input file
  89.         for the first valid delimiter it can find.
  90.  
  91.  
  92.   TO SEND A BINARY FILE
  93.  
  94.   From the DOS command line, type "XX3402" followed by the parameter
  95.   "E" (encode binary file, placing all encoded text blocks into a
  96.   single output file) or "ES" (encode binary file, and split all
  97.   encoded text blocks into separate output files), followed by the
  98.   name of the binary file you want to encode.
  99.  
  100.     ie: XX3402 ES FILENAME.ZIP
  101.  
  102.   This will create a series of encoded text files, with the
  103.   filenames:  FILENAME.X01, FILENAME.X02, FILENAME.X03, ETC...
  104.  
  105.   You can then send these encoded text files via E-mail.
  106.   Make sure you only post *complete* encoded text blocks.
  107.   Do *not* split an encoded text block, as this will very
  108.   likely corrupt the encoded block you are sending.
  109.  
  110.   NOTE: You can change the size of the encoded block size via
  111.   parameter 3 (column width) and parameter 4 (row length),
  112.   when encoding.
  113.  
  114.  
  115.   TO DECODE AN ENCODED FILE
  116.  
  117.   Capture all encoded blocks you receive to a text file, in any
  118.   order. Next feed this capture file with all the normal E-mail
  119.   header/footer lines of text intact. (ie: No editing required)
  120.  
  121.   From the DOS command line, type "XX3402" followed by the
  122.   parameter "D" (decode encoded text file) or "T" (Test the
  123.   integrity of individual encoded text blocks within the
  124.   capture file. Useful to test if individual encoded blocks
  125.   are corrupt.), followed by the name of the capture file
  126.   you want to decode or test.
  127.  
  128.     ie: XX3402 D FILENAME.TXT
  129.  
  130.   The XX3402 utility will automatically: find, sort, error-check,
  131.   and finally decode the encoded text blocks into a copy of the
  132.   original binary file. The whole decoding process if quite fast.
  133.  
  134.  
  135.   WHY BUILD ANOTHER ONE ?
  136.  
  137.   Originally this utility started out as a simple project to improve
  138.   my Pascal skills. After trying out a few standard UU/XX encoder
  139.   utilities, I decided to try to build one of my own.
  140.  
  141.   To try and improve upon the "ease of use" and error-checking
  142.   performance of the standard XX/UU encoders, I decided to add
  143.   a "header" at the beginning of each encoded text block.
  144.  
  145.  
  146.   XX34 HEADER FORMAT
  147.  
  148.      *XX3402-050000-280194--72--85-54219----FILENAME.EXT--1-OF-12
  149.  
  150.            *  - Delimiter character. (Part of the XX34 ID)
  151.                 Used to find each encoded text block when decoding.
  152.                 Nine alternative delimiters can be used, using the
  153.                 5th parameter when encoding.
  154.  
  155.        XX3402 - XX34 identifying signature, incorporating the version
  156.                 number.
  157.  
  158.       050000  - Original (non-encoded) binary file size. XX3402 has
  159.                 a file size capacity of 103,275..11,455,875 bytes,
  160.                 depending on the encoded text block dimensions.
  161.                 (Default capacity is: 1,156,680 bytes)
  162.  
  163.       280194  - Original binary file date.
  164.                 (ie: 28th of January, 1994)
  165.  
  166.           72  - Encoded block column width.
  167.                 (ie: 60..100 chars wide, in increments of 4)
  168.  
  169.           85  - Encoded block row length.
  170.                 (ie: 10..600 rows long, in increments of 1)
  171.  
  172.        54219  - CRC-16 value for the original binary "block", used
  173.                 to insure that the decoded binary file is identical
  174.                 to the original binary-file.
  175.  
  176.     FILENAME  - Original binary file name.
  177.  
  178.         .EXT  - Original binary file extension.
  179.  
  180.      1-OF-12  - Encoded text block number, and the total number of
  181.                 encoded text blocks required to encode the original
  182.                 binary file. (ie: Block number 1, of a total of 12)
  183.  
  184.   NOTE: When more than 99 encoded text blocks are required to
  185.         encode the original binary file, XX34 switches to
  186.         hexadecimal numbering. This also occurs if the original
  187.         binary file is greater than 999,999 bytes in size.
  188.         (Hexadecimal numbering is indicated by the character 'H'
  189.          after the CRC-16 value in the XX34 header.)
  190.  
  191.     ie: *XX3402-00C350-280194--60--10-43025-H--FILENAME.EXT--1-OF-7C
  192.                 ^^^^^^                      ^                ^    ^^
  193.                  Hex#                    Hex flag          Hex#  Hex#
  194.  
  195.  
  196.   ENCODING/DECODING BEHAVIOR
  197.  
  198.     - Check if input file exists.
  199.  
  200.     - Check if input file is a "zero-byte" file.
  201.  
  202.     - Check if input and output filenames are identical.
  203.  
  204.     - Prompt you to overwrite output file, if it already exists.
  205.  
  206.     - Check if output file is read-only.
  207.  
  208.     - Check if there is sufficient free memory to create encoding/
  209.       decoding buffers.
  210.  
  211.  
  212.   ENCODING BEHAVIOR
  213.  
  214.     - Check if column/row parameters passed are valid, otherwise
  215.       defaults are used.
  216.  
  217.     - Check if binary file is too big to encode using column/row
  218.       settings.
  219.  
  220.     - Incorporate size, date, and name of original binary file
  221.       into each encoded text block header.
  222.  
  223.  
  224.   DECODING BEHAVIOR
  225.  
  226.     - Search for valid XX34 identifier within the input file.
  227.  
  228.     - Search for all encoded text block headers within the input
  229.       file.
  230.  
  231.     - Check for missing or duplicate encoded text blocks.
  232.  
  233.     - Check binary file size stored within encoded text XX34 header.
  234.  
  235.     - Check that the binary file sizes and dates stored within all
  236.       encoded text headers match.
  237.  
  238.     - Check that the column/row sizes stored within all encoded text
  239.       headers match.
  240.  
  241.     - Check that the binary filename stored within all encoded text
  242.       headers match.
  243.  
  244.     - Check that the encoded text block total stored within all
  245.       encoded headers match.
  246.  
  247.     - Check if decoded binary file name already exists, allowing
  248.       user choose between: overwriting original file,
  249.                            abort decoding process,
  250.                            rename decoded output file.
  251.  
  252.     - Decode each encoded text block, in sorted order.
  253.  
  254.     - Compare the CRC-16 value stored within each encoded text block
  255.       header, with a new CRC-16 value calculated from the decoded
  256.       binary data. (This will catch corrupt encoded blocks.)
  257.  
  258.     - Write decoded binary data to disk.
  259.  
  260.     - Set the file date of new (decoded) binary file, to the same
  261.       date as the original binary file.
  262.  
  263.   NOTE: When decoding, XX3402 does NOT require that the encoded text
  264.         blocks be edited or in sorted order. You can simply capture
  265.         all encoded blocks to a text file, and then feed this file
  266.         to XX3402 to decode.
  267.  
  268.         If no errors are found when decoding, a new copy of the
  269.         original binary file will be created on disk. If an encoded
  270.         text block error is found, XX3402 will halt with an error
  271.         message indicating what the problem is.
  272.  
  273.  
  274.   ADDITIONAL INFO
  275.  
  276.     XX3402 requires between 64..160K of free memory to run, depending
  277.     on the encoded text block size used when encoding/decoding.
  278.  
  279.     The binary encoding capacity varies with the size of the encoded
  280.     text block used. The formula for determining the maximum binary
  281.     capacity for a specific encoded block size is:
  282.  
  283.           Binary Capacity = Columns * (Rows - 1) * 0.75 * 255
  284.  
  285.               Columns    Rows    Maximum Size (255 Blocks)
  286.               -------    ----    --------------------------
  287.                   60       10       103,275 bytes (   100K)
  288.                   72       85     1,156,680 bytes ( 1,129K)
  289.                   80      200     3,044,700 bytes ( 2,973K)
  290.                  100      400     7,611,750 bytes ( 7,433K)
  291.                  100      600    11,455,875 bytes (11,187K)
  292.  
  293.  
  294.  NOTE: Remember to archive (.ARC, .ARJ, .LHA, .ZIP, .ZOO) any file
  295.        you intend to encode, often this will greatly compress the
  296.        size of the binary file, resulting in a MUCH smaller encoded
  297.        text file. Most archiving formats will create an additional
  298.        level of CRC error checking, adding extra security to the
  299.        encoding/decoding process.
  300.  
  301.  
  302.   CREDITS
  303.  
  304.     XX3402.EXE was developed with Borland Pascal 7.01.
  305.  
  306.     The final .EXE was created with Stony Brook Pascal 6.1G.
  307.  
  308.     Thanks to Edwin T. Floyd's for releasing his excellent
  309.     "Crc" assembly unit. (Who was aided by the efforts of:
  310.     Gary S. Brown, Chuck Forsberg of Omen Technology,
  311.     J.R. Louvau, Mark G. Mendel of Network Systems Corporation,
  312.     Steven Satchell of Satchell Evaluations.)
  313.  
  314.     A BIG THANKS! to all the folks that helped me through my beta
  315.     tests of this utility. (A BIG "Raspberry" to all the bugs that
  316.     showed up in my source-code to torment me. <g>)
  317.  
  318.                                - Guy
  319.  
  320.     Comments/bug-reports can be passed on through the Pascal confs
  321.     on the following networks: FIDO, ILINK, NANET, RIME
  322.  
  323.     ...Or via "snail-mail":
  324.  
  325.       Guy McLoughlin
  326.       P.O. Box 519,
  327.       Station A,
  328.       Toronto, Ontario,
  329.       Canada M5W 1E4
  330.  
  331.